Best of Shareware/Best of PC Windows Shareware 1.0 - Wayzata Technology (7111) (1993).iso/mac/DOS/PROGRAMG/GRAD/GRAD.DOC

Text File | 1993-01-07 | 10KB | 203 lines

            GRAD: AUTOMATIC DIFFERENTIATION OF FORTRAN PROGRAMS

                        USER NOTES  -  January 1993


INTRODUCTION

The computation of partial derivatives is required in optimization,
parameter estimation, sensitivity analysis, and other problems.  With
complicated functions, the coding of derivative computations can be
laborious and error-prone and, in many instances, impractical.  When the
number of variables is large, the alternative of using finite difference
approximations is computationally costly, with many function evaluations
required to compute a gradient.  Symbolic algebra packages can sometimes be
used to generate the derivatives.  These packages may be inadequate,
however, when the functions to be differentiated are defined by computer
programs including intermediate variables, loops, and conditionals.

The system described here, GRAD, does most of the work of generating a
Fortran subprogram for computing the gradient, given a Fortran subrprogram
that computes the function.  It has been used successfully since 1988 for
maximum-likelihood estimation in complex statistical models (García 1989,
1992).  GRAD has been implemented in the APL computer language, but no
knowledge of APL is required for its use.  Methods and implementation are
described elsewhere (García 1992; a file with part of a 1991 unpublished
report is included with this release).


SYSTEM REQUIREMENTS

This release contains a stand-alone executable file, GRAD.EXE, for
IBM-compatible PC's.  There are no special hardware requirements.

This is a port to IBM's APL2/PC of the STSC APL*PLUS version, converted to
a stand-alone executable with the APL2/PC packaging facility.  No attempt
was made to make use of the APL2 extended language features.  The sources
for this and the previous APL*PLUS and I-APL versions are available on
request.


FUNCTION CODING

The function to be differentiated is usually given by a Fortran SUBROUTINE
or FUNCTION subprogram.  It is also possible to process arbitrary Fortran
code segments.  The following restrictions must be observed in the coding
of the source function:

a) The independent variables must be scalars or array elements with
constant subscripts.  Array elements with variable subscripts, such as
X(I), may be misinterpreted without warning.  Also, the independent
variables must not be re-assigned (i.e. must not appear on the left-hand-
side of an assignment statement).  If necessary, you may introduce
auxilliary variables to work around these restrictions.

b) Values involving the independent variables directly or indirectly (i.e.
with non-zero partial derivatives) must be altered only by assignment
statements.  In particular, variable changes resulting from EQUIVALENCE,
READ and CALL statements are ignored without warning.

c) Assignments involving the independent variables directly or indirectly
are not allowed in IF statements.  An error message is produced.

d) Labels are not allowed in assignment statements involving the
independent variables directly or indirectly (use CONTINUE).  An error
message is produced.

e) Calling user-defined functions or FUNCTION subprograms involving the
independent variables directly or indirectly is not supported, and they
will be misinterpreted without warning.

f) The following functions are supported:  DABS, DLOG, DEXP, DSQRT, DSIN,
DCOS, DTAN, DASIN, DACOS, and DATAN.  The single-precision forms (ABS,
ALOG, etc., but not LOG) are also accepted, but the double-precision
version is used in the output, and a warning is produced.  The names must
be in upper-case.  Other functions are ignored without warning.

g) The COMPLEX data type is not supported.

h) Upper- or lower-case must be used consistenly in variable identifiers.
That is, a variable name must be always in upper-case or always in lower-
case (or have always the same mix of upper- and lower-case).

It is assumed that the input is valid Fortran, i.e., it has been compiled
with no errors.


RUNNING GRAD

Enter "GRAD" from DOS (do not type the quotes).  Then answer the screen
prompts.  The first prompt is for the input file name (the file with the
Fortran subprogram source to be differentiated).  Path names (e.g.
"D:\WRK\FUNC1.FOR") are acceptable (try the examples FUNC1.FOR, FUNC2.FOR
and FUNC3.FOR included with GRAD).  The second prompt is for an output file
name, where the output routine will be stored.

The next prompt is for the derivative index delimiter.  The identifiers for
the intermediate derivatives are formed by appending this delimiter and the
number of the independent variable to the identifiers on the left-hand-side
of assignments.  Press Enter to accept the default ("_", unless changed in
a previous run in this session).  If the default is not acceptable to your
compiler, or you want a different delimiter for any reason (e.g. for second
derivatives, see below), type it in and press Enter.  Note that in the APL
keyboard symbol locations may differ from those in the standard keyboard.
Warning: if a GRAD-generated name happens to coincide with an existing name
the results will be incorrect.

Finally, you must enter the names of the independent variables, separated
by "\" (spaces are not significant).  For the examples:
        FUNC1:  X\Y
        FUNC2:  X\Y\Z
        FUNC3:  X(1)\X(2)\X(3)\X(4)
If you require more than one screen line, end the line with a "\" which
will be interpreted as a continuation character.

GRAD starts then to output the code for the derivatives, both to the screen
and to the output file.  When finished, the message "Done" is displayed.
GRAD may terminate with an error message (possibly unintelligible) if there
are file errors or invalid Fortran statements.

MS-DOS pipes and input/output re-direction (use of |, <, and > on the
command line) are supported.

Second or higher derivatives can be generated simply by running the output
through GRAD.  Different delimiter characters for the identifiers must be
used in each run.  The resulting code, however, will perform redundant
computations, since (for second derivatives) two versions of the gradient
and of the off-diagonal Hessian elements are generated.  It would not be
difficult to eliminate this redundancy in a post-processing step, but this
has not been implemented.  You might be able to do this with a text editor
macro, or a short program in AWK.


OUTPUT

You must edit the header of the output routine to change its name and to
include the derivatives as arguments.  For example, suppose that the input
header was

      SUBROUTINE FUNC1(X, Y, Z, F) ,

where X, Y and Z are the independent variables, and F is the function
value.  Then the partial derivatives are assigned to the new variables F_1,
F_2 and F_3 just before the final assignment to F (assuming that the
default delimiter was used).  It is then necessary to change the header to
something like

      SUBROUTINE DERS1(X, Y, Z, F, F_1, F_2, F_3) .

If default types or IMPLICIT declarations are not used, it may also be
necessary to declare the new variables (including intermediate ones).

You must dimension any arrays created by GRAD.  These correspond to
derivatives of arrays in the source routine, and must have the same
dimension.

Error messages are included in the output in lines starting with " ***".
If ignored, they will be detected by the compiler.

Two types of warnings, starting with "C*** WARNING:", may be produced.
They may be left in the code as comments.  The first is "identifier too
long", and is produced when identifiers longer than the Fortran standard of
6 characters are generated.  Many compilers provide the option of accepting
long identifiers (for example with the switch /4Nt in Microsoft Fortran).
If your compiler does not, you would have to change those names with an
editor.

The other warning, "statement interpreted as...", indicates a discrepancy
between the source statement and the result of its parsing by GRAD.  This
is a safety feature, and should be triggered only by redundant parenthesis,
and by single-precision function names which are converted to their double-
precision form for output.

You may see in the output some ackward-looking expressions, such as
X**(2-1).  Do not worry, these are taken care off by the optimizer in any
decent Fortran compiler.

Some logical or character assignments may generate superfluous, but
harmless code.

If possible, it is recommended to check the generated subroutine by
comparison against finite differences.


REFERENCES

García, O. 1989.  Growth Modelling - New developments.  In: Nagumo, H. and
    Konohira, Y. (Ed.)  Japan and New Zealand Symposium on Forestry
    Management Planning.  Japan Association for Forestry Statistics.

García, O. 1992.  A system for the differentiation of Fortran code and an
    application to parameter estimation in forest growth models.  In:
    Griewank, A., and Corliss, G.F. (eds)  Automatic differentiation of
    algorithms:  theory, implementation and application.  Society for
    Industrial and Applied Mathematics, Philadelphia.


Oscar García
Instituto Forestal
Huerfanos 554
Santiago                  E-mail:   [e-mail]
CHILE                     Fax:      [phone]